Artemis Trouble Ticket API

API Overview

The TMF621 Trouble Ticket API provides a standardized interface for partners to raise, track, and manage trouble tickets related to broadband and voice services. It enables communication of service issues to PXC and supports both appointed and non-appointed fault scenarios.

This API aligns with TM Forum’s TMF621 v5.0.0 specification and forms part of the Strategic Assurance Management (SAM) platform, which aims to deliver a consistent and automated assurance experience across all strategic products (e.g., FTTP, SOGEA & Single Line Voice(VOIP)).

Disclaimer

Do not reuse sample values. Replace all identifiers, phone numbers, and contact details with your own test/production data.

All reserved terms in the examples are provided with a camel case format (i.e. "role": "relatedAccount”). All TMF metadata attributes are in Pascal case format (i.e. "@baseType": "ContactMedium”).

Key Capabilities

• Retrieve list of Trouble Ticket Specifications-
• Retrieve details of a Trouble Ticket Specification-
• Raise a new Trouble Ticket with fault details and attachments-
• Modify existing tickets (e.g., status, notes, appointment references)-
• Retrieve current ticket status and metadata-
• Receive event-driven updates (e.g., status changes, resolution notifications)

Authentication & Authorisation

Access is secured using OAuth 2.0 JWT issued by PXC’s partner identity platform. Only authenticated and authorized partners may access the API.

Standards Alignment

This API conforms to the TMF621 resource model and operational semantics, supporting core operations:

GET /troubleTicketSpecification/{id}
GET /troubleTicketSpecification
POST /troubleTicket
PATCH /troubleTicket/{id}
GET /troubleTicket/{id}
GET /troubleTicket
Notifications: TMF621-compliant event types

API Fundamentals

The TMF621 Trouble Ticket API supports the creation, update, and retrieval of assurance-related tickets via RESTful endpoints. It is designed according to TMF630 guidelines and is implemented with layered architecture to ensure scalability, traceability, and partner interoperability.

The API is built on REST principles using standard HTTP methods (POST, PATCH, GET) and uses JSON payloads for both requests and responses. Key resource types such as TroubleTicket, TroubleTicketSpecification, Note, and Attachment follow TMF schema patterns and support polymorphic extension via @type, @baseType, and @schemaLocation.

All interactions are secured via OAuth 2.0 JWT authentication issued by the Artemis partner identity platform. Partner-specific traceability is supported via optional Correlation-ID (UUID v4 (RFC 4122)) headers, and data minimization is achieved using field projection and filtering query parameters. If passed, the Correlation-ID will be returned to the consumer in the API response; otherwise a new Correlation-ID will be used to track the transaction.

This API enables seamless integration between external partners and internal processes through MuleSoft orchestration.

TMF Metadata Fields

TMF APIs use a set of metadata fields to support polymorphism, inheritance, and resource linking.

• @type: Specifies the concrete type of the object, especially when it is an extension of a base TMF resource. For example, @type: PartnerTroubleTicket indicates a specialization of the standard TroubleTicket.-
• @baseType: Indicates the base TMF resource from which the object inherits, such as TroubleTicket. This is useful for deserialization and tooling.-
• href: A full URI that points to the canonical location of the resource (e.g., GET /troubleTicket/{id}). It is mandatory in all GET responses for top-level and referenced resources, allowing clients to retrieve the full object via follow-up calls.-
• @schemaLocation (optional): Provides the URL of the JSON schema that defines the structure of the resource, mainly for validation or developer tooling.

These metadata fields are generally not required in POST or PATCH requests, but are mandatory in GET responses for compliance with TMF Open API standards.

Schema Extensions

To accommodate the current requirements, the API was extended using the @type field for custom classifications and the troubleTicketCharacteristic array for dynamic attributes. This supports flexible modelling of fault categories and appointment metadata without altering the base schema.

Where necessary, a subset of relatedEntity and relatedParty attributes were extended to carry additional context, such as Product ID, Access CASR, or appointment reference.

Authentication and Authorisation

The TMF621 Trouble Ticket API is hosted in Azure and exposed via the PXC API Gateway. It uses the OAuth2 protocol for client authentication using a client_id and client_secret. Once authenticated, a client receives a bearer token, which must be passed in the Authorization header for all API requests.

BillingAccountis required as a relatedEntity for authorization.